<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Tutorial</title>
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../mpi.html" title="Chapter&#160;19.&#160;Boost.MPI">
<link rel="prev" href="getting_started.html" title="Getting started">
<link rel="next" href="reference.html" title="Reference">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
<td align="center"><a href="../../../index.html">Home</a></td>
<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="getting_started.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../mpi.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="reference.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="mpi.tutorial"></a>Tutorial</h2></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="tutorial.html#mpi.point_to_point">Point-to-Point communication</a></span></dt>
<dt><span class="section"><a href="tutorial.html#mpi.collectives">Collective operations</a></span></dt>
<dt><span class="section"><a href="tutorial.html#mpi.communicators">Managing communicators</a></span></dt>
<dt><span class="section"><a href="tutorial.html#mpi.skeleton_and_content">Separating structure from content</a></span></dt>
<dt><span class="section"><a href="tutorial.html#mpi.performance_optimizations">Performance optimizations</a></span></dt>
<dt><span class="section"><a href="tutorial.html#mpi.c_mapping">Mapping from C MPI to Boost.MPI</a></span></dt>
</dl></div>
<p>
      A Boost.MPI program consists of many cooperating processes (possibly running
      on different computers) that communicate among themselves by passing messages.
      Boost.MPI is a library (as is the lower-level MPI), not a language, so the
      first step in a Boost.MPI is to create an <code class="computeroutput"><a class="link" href="../boost/mpi/environment.html" title="Class environment">mpi::environment</a></code>
      object that initializes the MPI environment and enables communication among
      the processes. The <code class="computeroutput"><a class="link" href="../boost/mpi/environment.html" title="Class environment">mpi::environment</a></code>
      object is initialized with the program arguments (which it may modify) in your
      main program. The creation of this object initializes MPI, and its destruction
      will finalize MPI. In the vast majority of Boost.MPI programs, an instance
      of <code class="computeroutput"><a class="link" href="../boost/mpi/environment.html" title="Class environment">mpi::environment</a></code> will
      be declared in <code class="computeroutput"><span class="identifier">main</span></code> at the
      very beginning of the program.
    </p>
<p>
      Communication with MPI always occurs over a <span class="bold"><strong>communicator</strong></span>,
      which can be created be simply default-constructing an object of type <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html" title="Class communicator">mpi::communicator</a></code>. This communicator
      can then be queried to determine how many processes are running (the "size"
      of the communicator) and to give a unique number to each process, from zero
      to the size of the communicator (i.e., the "rank" of the process):
    </p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">mpi</span><span class="special">/</span><span class="identifier">environment</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">mpi</span><span class="special">/</span><span class="identifier">communicator</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
<span class="keyword">namespace</span> <span class="identifier">mpi</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mpi</span><span class="special">;</span>

<span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">argc</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">argv</span><span class="special">[])</span>
<span class="special">{</span>
  <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">environment</span> <span class="identifier">env</span><span class="special">(</span><span class="identifier">argc</span><span class="special">,</span> <span class="identifier">argv</span><span class="special">);</span>
  <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">communicator</span> <span class="identifier">world</span><span class="special">;</span>
  <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"I am process "</span> <span class="special">&lt;&lt;</span> <span class="identifier">world</span><span class="special">.</span><span class="identifier">rank</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">" of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">world</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span>
            <span class="special">&lt;&lt;</span> <span class="string">"."</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
  <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
      If you run this program with 7 processes, for instance, you will receive output
      such as:
    </p>
<pre class="programlisting">I am process 5 of 7.
I am process 0 of 7.
I am process 1 of 7.
I am process 6 of 7.
I am process 2 of 7.
I am process 4 of 7.
I am process 3 of 7.
</pre>
<p>
      Of course, the processes can execute in a different order each time, so the
      ranks might not be strictly increasing. More interestingly, the text could
      come out completely garbled, because one process can start writing "I
      am a process" before another process has finished writing "of 7.".
    </p>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="mpi.point_to_point"></a>Point-to-Point communication</h3></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="tutorial.html#mpi.nonblocking">Non-blocking communication</a></span></dt>
<dt><span class="section"><a href="tutorial.html#mpi.user_data_types">User-defined data types</a></span></dt>
</dl></div>
<p>
        As a message passing library, MPI's primary purpose is to routine messages
        from one process to another, i.e., point-to-point. MPI contains routines
        that can send messages, receive messages, and query whether messages are
        available. Each message has a source process, a target process, a tag, and
        a payload containing arbitrary data. The source and target processes are
        the ranks of the sender and receiver of the message, respectively. Tags are
        integers that allow the receiver to distinguish between different messages
        coming from the same sender.
      </p>
<p>
        The following program uses two MPI processes to write "Hello, world!"
        to the screen (<code class="computeroutput"><span class="identifier">hello_world</span><span class="special">.</span><span class="identifier">cpp</span></code>):
      </p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">mpi</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">string</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">serialization</span><span class="special">/</span><span class="identifier">string</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">namespace</span> <span class="identifier">mpi</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mpi</span><span class="special">;</span>

<span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">argc</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">argv</span><span class="special">[])</span>
<span class="special">{</span>
  <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">environment</span> <span class="identifier">env</span><span class="special">(</span><span class="identifier">argc</span><span class="special">,</span> <span class="identifier">argv</span><span class="special">);</span>
  <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">communicator</span> <span class="identifier">world</span><span class="special">;</span>

  <span class="keyword">if</span> <span class="special">(</span><span class="identifier">world</span><span class="special">.</span><span class="identifier">rank</span><span class="special">()</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span> <span class="special">{</span>
    <span class="identifier">world</span><span class="special">.</span><span class="identifier">send</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">(</span><span class="string">"Hello"</span><span class="special">));</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">msg</span><span class="special">;</span>
    <span class="identifier">world</span><span class="special">.</span><span class="identifier">recv</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">1</span><span class="special">,</span> <span class="identifier">msg</span><span class="special">);</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">msg</span> <span class="special">&lt;&lt;</span> <span class="string">"!"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
  <span class="special">}</span> <span class="keyword">else</span> <span class="special">{</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">msg</span><span class="special">;</span>
    <span class="identifier">world</span><span class="special">.</span><span class="identifier">recv</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">msg</span><span class="special">);</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">msg</span> <span class="special">&lt;&lt;</span> <span class="string">", "</span><span class="special">;</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">.</span><span class="identifier">flush</span><span class="special">();</span>
    <span class="identifier">world</span><span class="special">.</span><span class="identifier">send</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="number">1</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">(</span><span class="string">"world"</span><span class="special">));</span>
  <span class="special">}</span>

  <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
        The first processor (rank 0) passes the message "Hello" to the
        second processor (rank 1) using tag 0. The second processor prints the string
        it receives, along with a comma, then passes the message "world"
        back to processor 0 with a different tag. The first processor then writes
        this message with the "!" and exits. All sends are accomplished
        with the <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp43887088-bb">communicator::send</a></code>
        method and all receives use a corresponding <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp44013376-bb">communicator::recv</a></code>
        call.
      </p>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="mpi.nonblocking"></a>Non-blocking communication</h4></div></div></div>
<p>
          The default MPI communication operations--<code class="computeroutput"><span class="identifier">send</span></code>
          and <code class="computeroutput"><span class="identifier">recv</span></code>--may have to wait
          until the entire transmission is completed before they can return. Sometimes
          this <span class="bold"><strong>blocking</strong></span> behavior has a negative
          impact on performance, because the sender could be performing useful computation
          while it is waiting for the transmission to occur. More important, however,
          are the cases where several communication operations must occur simultaneously,
          e.g., a process will both send and receive at the same time.
        </p>
<p>
          Let's revisit our "Hello, world!" program from the previous section.
          The core of this program transmits two messages:
        </p>
<pre class="programlisting"><span class="keyword">if</span> <span class="special">(</span><span class="identifier">world</span><span class="special">.</span><span class="identifier">rank</span><span class="special">()</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span> <span class="special">{</span>
  <span class="identifier">world</span><span class="special">.</span><span class="identifier">send</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">(</span><span class="string">"Hello"</span><span class="special">));</span>
  <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">msg</span><span class="special">;</span>
  <span class="identifier">world</span><span class="special">.</span><span class="identifier">recv</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">1</span><span class="special">,</span> <span class="identifier">msg</span><span class="special">);</span>
  <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">msg</span> <span class="special">&lt;&lt;</span> <span class="string">"!"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="special">}</span> <span class="keyword">else</span> <span class="special">{</span>
  <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">msg</span><span class="special">;</span>
  <span class="identifier">world</span><span class="special">.</span><span class="identifier">recv</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">msg</span><span class="special">);</span>
  <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">msg</span> <span class="special">&lt;&lt;</span> <span class="string">", "</span><span class="special">;</span>
  <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">.</span><span class="identifier">flush</span><span class="special">();</span>
  <span class="identifier">world</span><span class="special">.</span><span class="identifier">send</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="number">1</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">(</span><span class="string">"world"</span><span class="special">));</span>
<span class="special">}</span>
</pre>
<p>
          The first process passes a message to the second process, then prepares
          to receive a message. The second process does the send and receive in the
          opposite order. However, this sequence of events is just that--a <span class="bold"><strong>sequence</strong></span>--meaning that there is essentially no parallelism.
          We can use non-blocking communication to ensure that the two messages are
          transmitted simultaneously (<code class="computeroutput"><span class="identifier">hello_world_nonblocking</span><span class="special">.</span><span class="identifier">cpp</span></code>):
        </p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">mpi</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">string</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">serialization</span><span class="special">/</span><span class="identifier">string</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">namespace</span> <span class="identifier">mpi</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mpi</span><span class="special">;</span>

<span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">argc</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">argv</span><span class="special">[])</span>
<span class="special">{</span>
  <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">environment</span> <span class="identifier">env</span><span class="special">(</span><span class="identifier">argc</span><span class="special">,</span> <span class="identifier">argv</span><span class="special">);</span>
  <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">communicator</span> <span class="identifier">world</span><span class="special">;</span>

  <span class="keyword">if</span> <span class="special">(</span><span class="identifier">world</span><span class="special">.</span><span class="identifier">rank</span><span class="special">()</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span> <span class="special">{</span>
    <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">request</span> <span class="identifier">reqs</span><span class="special">[</span><span class="number">2</span><span class="special">];</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">msg</span><span class="special">,</span> <span class="identifier">out_msg</span> <span class="special">=</span> <span class="string">"Hello"</span><span class="special">;</span>
    <span class="identifier">reqs</span><span class="special">[</span><span class="number">0</span><span class="special">]</span> <span class="special">=</span> <span class="identifier">world</span><span class="special">.</span><span class="identifier">isend</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">out_msg</span><span class="special">);</span>
    <span class="identifier">reqs</span><span class="special">[</span><span class="number">1</span><span class="special">]</span> <span class="special">=</span> <span class="identifier">world</span><span class="special">.</span><span class="identifier">irecv</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">1</span><span class="special">,</span> <span class="identifier">msg</span><span class="special">);</span>
    <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">wait_all</span><span class="special">(</span><span class="identifier">reqs</span><span class="special">,</span> <span class="identifier">reqs</span> <span class="special">+</span> <span class="number">2</span><span class="special">);</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">msg</span> <span class="special">&lt;&lt;</span> <span class="string">"!"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
  <span class="special">}</span> <span class="keyword">else</span> <span class="special">{</span>
    <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">request</span> <span class="identifier">reqs</span><span class="special">[</span><span class="number">2</span><span class="special">];</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">msg</span><span class="special">,</span> <span class="identifier">out_msg</span> <span class="special">=</span> <span class="string">"world"</span><span class="special">;</span>
    <span class="identifier">reqs</span><span class="special">[</span><span class="number">0</span><span class="special">]</span> <span class="special">=</span> <span class="identifier">world</span><span class="special">.</span><span class="identifier">isend</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="number">1</span><span class="special">,</span> <span class="identifier">out_msg</span><span class="special">);</span>
    <span class="identifier">reqs</span><span class="special">[</span><span class="number">1</span><span class="special">]</span> <span class="special">=</span> <span class="identifier">world</span><span class="special">.</span><span class="identifier">irecv</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">msg</span><span class="special">);</span>
    <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">wait_all</span><span class="special">(</span><span class="identifier">reqs</span><span class="special">,</span> <span class="identifier">reqs</span> <span class="special">+</span> <span class="number">2</span><span class="special">);</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">msg</span> <span class="special">&lt;&lt;</span> <span class="string">", "</span><span class="special">;</span>
  <span class="special">}</span>

  <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
          We have replaced calls to the <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp43887088-bb">communicator::send</a></code>
          and <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp44013376-bb">communicator::recv</a></code>
          members with similar calls to their non-blocking counterparts, <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp44039536-bb">communicator::isend</a></code>
          and <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp44061216-bb">communicator::irecv</a></code>.
          The prefix <span class="bold"><strong>i</strong></span> indicates that the operations
          return immediately with a <code class="computeroutput"><a class="link" href="../boost/mpi/request.html" title="Class request">mpi::request</a></code>
          object, which allows one to query the status of a communication request
          (see the <code class="computeroutput"><a class="link" href="../boost/mpi/request.html#idp44203776-bb">test</a></code>
          method) or wait until it has completed (see the <code class="computeroutput"><a class="link" href="../boost/mpi/request.html#idp44202704-bb">wait</a></code>
          method). Multiple requests can be completed at the same time with the
          <code class="computeroutput"><a class="link" href="../boost/mpi/wait_all.html" title="Function wait_all">wait_all</a></code> operation.
        </p>
<p>
          If you run this program multiple times, you may see some strange results:
          namely, some runs will produce:
        </p>
<pre class="programlisting"><span class="identifier">Hello</span><span class="special">,</span> <span class="identifier">world</span><span class="special">!</span>
</pre>
<p>
          while others will produce:
        </p>
<pre class="programlisting"><span class="identifier">world</span><span class="special">!</span>
<span class="identifier">Hello</span><span class="special">,</span>
</pre>
<p>
          or even some garbled version of the letters in "Hello" and "world".
          This indicates that there is some parallelism in the program, because after
          both messages are (simultaneously) transmitted, both processes will concurrent
          execute their print statements. For both performance and correctness, non-blocking
          communication operations are critical to many parallel applications using
          MPI.
        </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="mpi.user_data_types"></a>User-defined data types</h4></div></div></div>
<p>
          The inclusion of <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">serialization</span><span class="special">/</span><span class="identifier">string</span><span class="special">.</span><span class="identifier">hpp</span></code>
          in the previous examples is very important: it makes values of type <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code> serializable, so that they can
          be be transmitted using Boost.MPI. In general, built-in C++ types (<code class="computeroutput"><span class="keyword">int</span></code>s, <code class="computeroutput"><span class="keyword">float</span></code>s,
          characters, etc.) can be transmitted over MPI directly, while user-defined
          and library-defined types will need to first be serialized (packed) into
          a format that is amenable to transmission. Boost.MPI relies on the <a href="http://www.boost.org/libs/serialization/doc" target="_top">Boost.Serialization</a>
          library to serialize and deserialize data types.
        </p>
<p>
          For types defined by the standard library (such as <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code>
          or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code>) and some types in Boost (such
          as <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">variant</span></code>), the <a href="http://www.boost.org/libs/serialization/doc" target="_top">Boost.Serialization</a>
          library already contains all of the required serialization code. In these
          cases, you need only include the appropriate header from the <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">serialization</span></code> directory.
        </p>
<p>
          For types that do not already have a serialization header, you will first
          need to implement serialization code before the types can be transmitted
          using Boost.MPI. Consider a simple class <code class="computeroutput"><span class="identifier">gps_position</span></code>
          that contains members <code class="computeroutput"><span class="identifier">degrees</span></code>,
          <code class="computeroutput"><span class="identifier">minutes</span></code>, and <code class="computeroutput"><span class="identifier">seconds</span></code>. This class is made serializable
          by making it a friend of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">serialization</span><span class="special">::</span><span class="identifier">access</span></code>
          and introducing the templated <code class="computeroutput"><span class="identifier">serialize</span><span class="special">()</span></code> function, as follows:
        </p>
<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">gps_position</span>
<span class="special">{</span>
<span class="keyword">private</span><span class="special">:</span>
    <span class="keyword">friend</span> <span class="keyword">class</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">serialization</span><span class="special">::</span><span class="identifier">access</span><span class="special">;</span>

    <span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Archive</span><span class="special">&gt;</span>
    <span class="keyword">void</span> <span class="identifier">serialize</span><span class="special">(</span><span class="identifier">Archive</span> <span class="special">&amp;</span> <span class="identifier">ar</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">version</span><span class="special">)</span>
    <span class="special">{</span>
        <span class="identifier">ar</span> <span class="special">&amp;</span> <span class="identifier">degrees</span><span class="special">;</span>
        <span class="identifier">ar</span> <span class="special">&amp;</span> <span class="identifier">minutes</span><span class="special">;</span>
        <span class="identifier">ar</span> <span class="special">&amp;</span> <span class="identifier">seconds</span><span class="special">;</span>
    <span class="special">}</span>

    <span class="keyword">int</span> <span class="identifier">degrees</span><span class="special">;</span>
    <span class="keyword">int</span> <span class="identifier">minutes</span><span class="special">;</span>
    <span class="keyword">float</span> <span class="identifier">seconds</span><span class="special">;</span>
<span class="keyword">public</span><span class="special">:</span>
    <span class="identifier">gps_position</span><span class="special">(){};</span>
    <span class="identifier">gps_position</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">d</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">m</span><span class="special">,</span> <span class="keyword">float</span> <span class="identifier">s</span><span class="special">)</span> <span class="special">:</span>
        <span class="identifier">degrees</span><span class="special">(</span><span class="identifier">d</span><span class="special">),</span> <span class="identifier">minutes</span><span class="special">(</span><span class="identifier">m</span><span class="special">),</span> <span class="identifier">seconds</span><span class="special">(</span><span class="identifier">s</span><span class="special">)</span>
    <span class="special">{}</span>
<span class="special">};</span>
</pre>
<p>
          Complete information about making types serializable is beyond the scope
          of this tutorial. For more information, please see the <a href="http://www.boost.org/libs/serialization/doc" target="_top">Boost.Serialization</a>
          library tutorial from which the above example was extracted. One important
          side benefit of making types serializable for Boost.MPI is that they become
          serializable for any other usage, such as storing the objects to disk to
          manipulated them in XML.
        </p>
<p>
          Some serializable types, like <code class="computeroutput"><span class="identifier">gps_position</span></code>
          above, have a fixed amount of data stored at fixed field positions. When
          this is the case, Boost.MPI can optimize their serialization and transmission
          to avoid extraneous copy operations. To enable this optimization, users
          should specialize the type trait <code class="computeroutput"><a class="link" href="../boost/mpi/is_mpi_datatype.html" title="Struct template is_mpi_datatype">is_mpi_datatype</a></code>, e.g.:
        </p>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">mpi</span> <span class="special">{</span>
  <span class="keyword">template</span> <span class="special">&lt;&gt;</span>
  <span class="keyword">struct</span> <span class="identifier">is_mpi_datatype</span><span class="special">&lt;</span><span class="identifier">gps_position</span><span class="special">&gt;</span> <span class="special">:</span> <span class="identifier">mpl</span><span class="special">::</span><span class="identifier">true_</span> <span class="special">{</span> <span class="special">};</span>
<span class="special">}</span> <span class="special">}</span>
</pre>
<p>
          For non-template types we have defined a macro to simplify declaring a
          type as an MPI datatype
        </p>
<pre class="programlisting"><span class="identifier">BOOST_IS_MPI_DATATYPE</span><span class="special">(</span><span class="identifier">gps_position</span><span class="special">)</span>
</pre>
<p>
          For composite traits, the specialization of <code class="computeroutput"><a class="link" href="../boost/mpi/is_mpi_datatype.html" title="Struct template is_mpi_datatype">is_mpi_datatype</a></code> may depend
          on <code class="computeroutput"><span class="identifier">is_mpi_datatype</span></code> itself.
          For instance, a <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span></code> object is fixed only when the type
          of the parameter it stores is fixed:
        </p>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">mpi</span> <span class="special">{</span>
  <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">T</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">N</span><span class="special">&gt;</span>
  <span class="keyword">struct</span> <span class="identifier">is_mpi_datatype</span><span class="special">&lt;</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">N</span><span class="special">&gt;</span> <span class="special">&gt;</span>
    <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">is_mpi_datatype</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="special">{</span> <span class="special">};</span>
<span class="special">}</span> <span class="special">}</span>
</pre>
<p>
          The redundant copy elimination optimization can only be applied when the
          shape of the data type is completely fixed. Variable-length types (e.g.,
          strings, linked lists) and types that store pointers cannot use the optimiation,
          but Boost.MPI will be unable to detect this error at compile time. Attempting
          to perform this optimization when it is not correct will likely result
          in segmentation faults and other strange program behavior.
        </p>
<p>
          Boost.MPI can transmit any user-defined data type from one process to another.
          Built-in types can be transmitted without any extra effort; library-defined
          types require the inclusion of a serialization header; and user-defined
          types will require the addition of serialization code. Fixed data types
          can be optimized for transmission using the <code class="computeroutput"><a class="link" href="../boost/mpi/is_mpi_datatype.html" title="Struct template is_mpi_datatype">is_mpi_datatype</a></code> type trait.
        </p>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="mpi.collectives"></a>Collective operations</h3></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="tutorial.html#mpi.broadcast">Broadcast</a></span></dt>
<dt><span class="section"><a href="tutorial.html#mpi.gather">Gather</a></span></dt>
<dt><span class="section"><a href="tutorial.html#mpi.reduce">Reduce</a></span></dt>
</dl></div>
<p>
        <a class="link" href="tutorial.html#mpi.point_to_point" title="Point-to-Point communication">Point-to-point operations</a> are the
        core message passing primitives in Boost.MPI. However, many message-passing
        applications also require higher-level communication algorithms that combine
        or summarize the data stored on many different processes. These algorithms
        support many common tasks such as "broadcast this value to all processes",
        "compute the sum of the values on all processors" or "find
        the global minimum."
      </p>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="mpi.broadcast"></a>Broadcast</h4></div></div></div>
<p>
          The <code class="computeroutput"><a class="link" href="../boost/mpi/broadcast.html" title="Function broadcast">broadcast</a></code>
          algorithm is by far the simplest collective operation. It broadcasts a
          value from a single process to all other processes within a <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html" title="Class communicator">communicator</a></code>. For instance,
          the following program broadcasts "Hello, World!" from process
          0 to every other process. (<code class="computeroutput"><span class="identifier">hello_world_broadcast</span><span class="special">.</span><span class="identifier">cpp</span></code>)
        </p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">mpi</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">string</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">serialization</span><span class="special">/</span><span class="identifier">string</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">namespace</span> <span class="identifier">mpi</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mpi</span><span class="special">;</span>

<span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">argc</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">argv</span><span class="special">[])</span>
<span class="special">{</span>
  <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">environment</span> <span class="identifier">env</span><span class="special">(</span><span class="identifier">argc</span><span class="special">,</span> <span class="identifier">argv</span><span class="special">);</span>
  <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">communicator</span> <span class="identifier">world</span><span class="special">;</span>

  <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">value</span><span class="special">;</span>
  <span class="keyword">if</span> <span class="special">(</span><span class="identifier">world</span><span class="special">.</span><span class="identifier">rank</span><span class="special">()</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span> <span class="special">{</span>
    <span class="identifier">value</span> <span class="special">=</span> <span class="string">"Hello, World!"</span><span class="special">;</span>
  <span class="special">}</span>

  <span class="identifier">broadcast</span><span class="special">(</span><span class="identifier">world</span><span class="special">,</span> <span class="identifier">value</span><span class="special">,</span> <span class="number">0</span><span class="special">);</span>

  <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Process #"</span> <span class="special">&lt;&lt;</span> <span class="identifier">world</span><span class="special">.</span><span class="identifier">rank</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">" says "</span> <span class="special">&lt;&lt;</span> <span class="identifier">value</span>
            <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
  <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
          Running this program with seven processes will produce a result such as:
        </p>
<pre class="programlisting">Process #0 says Hello, World!
Process #2 says Hello, World!
Process #1 says Hello, World!
Process #4 says Hello, World!
Process #3 says Hello, World!
Process #5 says Hello, World!
Process #6 says Hello, World!
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="mpi.gather"></a>Gather</h4></div></div></div>
<p>
          The <code class="computeroutput"><a class="link" href="../boost/mpi/gather.html" title="Function gather">gather</a></code>
          collective gathers the values produced by every process in a communicator
          into a vector of values on the "root" process (specified by an
          argument to <code class="computeroutput"><span class="identifier">gather</span></code>). The
          /i/th element in the vector will correspond to the value gathered fro mthe
          /i/th process. For instance, in the following program each process computes
          its own random number. All of these random numbers are gathered at process
          0 (the "root" in this case), which prints out the values that
          correspond to each processor. (<code class="computeroutput"><span class="identifier">random_gather</span><span class="special">.</span><span class="identifier">cpp</span></code>)
        </p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">mpi</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">vector</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cstdlib</span><span class="special">&gt;</span>
<span class="keyword">namespace</span> <span class="identifier">mpi</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mpi</span><span class="special">;</span>

<span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">argc</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">argv</span><span class="special">[])</span>
<span class="special">{</span>
  <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">environment</span> <span class="identifier">env</span><span class="special">(</span><span class="identifier">argc</span><span class="special">,</span> <span class="identifier">argv</span><span class="special">);</span>
  <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">communicator</span> <span class="identifier">world</span><span class="special">;</span>

  <span class="identifier">std</span><span class="special">::</span><span class="identifier">srand</span><span class="special">(</span><span class="identifier">time</span><span class="special">(</span><span class="number">0</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">world</span><span class="special">.</span><span class="identifier">rank</span><span class="special">());</span>
  <span class="keyword">int</span> <span class="identifier">my_number</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">rand</span><span class="special">();</span>
  <span class="keyword">if</span> <span class="special">(</span><span class="identifier">world</span><span class="special">.</span><span class="identifier">rank</span><span class="special">()</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span> <span class="special">{</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">all_numbers</span><span class="special">;</span>
    <span class="identifier">gather</span><span class="special">(</span><span class="identifier">world</span><span class="special">,</span> <span class="identifier">my_number</span><span class="special">,</span> <span class="identifier">all_numbers</span><span class="special">,</span> <span class="number">0</span><span class="special">);</span>
    <span class="keyword">for</span> <span class="special">(</span><span class="keyword">int</span> <span class="identifier">proc</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">proc</span> <span class="special">&lt;</span> <span class="identifier">world</span><span class="special">.</span><span class="identifier">size</span><span class="special">();</span> <span class="special">++</span><span class="identifier">proc</span><span class="special">)</span>
      <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Process #"</span> <span class="special">&lt;&lt;</span> <span class="identifier">proc</span> <span class="special">&lt;&lt;</span> <span class="string">" thought of "</span>
                <span class="special">&lt;&lt;</span> <span class="identifier">all_numbers</span><span class="special">[</span><span class="identifier">proc</span><span class="special">]</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
  <span class="special">}</span> <span class="keyword">else</span> <span class="special">{</span>
    <span class="identifier">gather</span><span class="special">(</span><span class="identifier">world</span><span class="special">,</span> <span class="identifier">my_number</span><span class="special">,</span> <span class="number">0</span><span class="special">);</span>
  <span class="special">}</span>

  <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
          Executing this program with seven processes will result in output such
          as the following. Although the random values will change from one run to
          the next, the order of the processes in the output will remain the same
          because only process 0 writes to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span></code>.
        </p>
<pre class="programlisting">Process #0 thought of 332199874
Process #1 thought of 20145617
Process #2 thought of 1862420122
Process #3 thought of 480422940
Process #4 thought of 1253380219
Process #5 thought of 949458815
Process #6 thought of 650073868
</pre>
<p>
          The <code class="computeroutput"><span class="identifier">gather</span></code> operation collects
          values from every process into a vector at one process. If instead the
          values from every process need to be collected into identical vectors on
          every process, use the <code class="computeroutput"><a class="link" href="../boost/mpi/all_gather.html" title="Function all_gather">all_gather</a></code> algorithm,
          which is semantically equivalent to calling <code class="computeroutput"><span class="identifier">gather</span></code>
          followed by a <code class="computeroutput"><span class="identifier">broadcast</span></code>
          of the resulting vector.
        </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="mpi.reduce"></a>Reduce</h4></div></div></div>
<p>
          The <code class="computeroutput"><a class="link" href="../boost/mpi/reduce.html" title="Function reduce">reduce</a></code>
          collective summarizes the values from each process into a single value
          at the user-specified "root" process. The Boost.MPI <code class="computeroutput"><span class="identifier">reduce</span></code> operation is similar in spirit
          to the STL <a href="http://www.sgi.com/tech/stl/accumulate.html" target="_top"><code class="computeroutput"><span class="identifier">accumulate</span></code></a> operation, because
          it takes a sequence of values (one per process) and combines them via a
          function object. For instance, we can randomly generate values in each
          process and the compute the minimum value over all processes via a call
          to <code class="computeroutput"><a class="link" href="../boost/mpi/reduce.html" title="Function reduce">reduce</a></code>
          (<code class="computeroutput"><span class="identifier">random_min</span><span class="special">.</span><span class="identifier">cpp</span></code>)::
        </p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">mpi</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cstdlib</span><span class="special">&gt;</span>
<span class="keyword">namespace</span> <span class="identifier">mpi</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mpi</span><span class="special">;</span>

<span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">argc</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">argv</span><span class="special">[])</span>
<span class="special">{</span>
  <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">environment</span> <span class="identifier">env</span><span class="special">(</span><span class="identifier">argc</span><span class="special">,</span> <span class="identifier">argv</span><span class="special">);</span>
  <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">communicator</span> <span class="identifier">world</span><span class="special">;</span>

  <span class="identifier">std</span><span class="special">::</span><span class="identifier">srand</span><span class="special">(</span><span class="identifier">time</span><span class="special">(</span><span class="number">0</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">world</span><span class="special">.</span><span class="identifier">rank</span><span class="special">());</span>
  <span class="keyword">int</span> <span class="identifier">my_number</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">rand</span><span class="special">();</span>

  <span class="keyword">if</span> <span class="special">(</span><span class="identifier">world</span><span class="special">.</span><span class="identifier">rank</span><span class="special">()</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span> <span class="special">{</span>
    <span class="keyword">int</span> <span class="identifier">minimum</span><span class="special">;</span>
    <span class="identifier">reduce</span><span class="special">(</span><span class="identifier">world</span><span class="special">,</span> <span class="identifier">my_number</span><span class="special">,</span> <span class="identifier">minimum</span><span class="special">,</span> <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">minimum</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(),</span> <span class="number">0</span><span class="special">);</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"The minimum value is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">minimum</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
  <span class="special">}</span> <span class="keyword">else</span> <span class="special">{</span>
    <span class="identifier">reduce</span><span class="special">(</span><span class="identifier">world</span><span class="special">,</span> <span class="identifier">my_number</span><span class="special">,</span> <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">minimum</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(),</span> <span class="number">0</span><span class="special">);</span>
  <span class="special">}</span>

  <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
          The use of <code class="computeroutput"><span class="identifier">mpi</span><span class="special">::</span><span class="identifier">minimum</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span></code>
          indicates that the minimum value should be computed. <code class="computeroutput"><span class="identifier">mpi</span><span class="special">::</span><span class="identifier">minimum</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span></code> is a binary function object that compares
          its two parameters via <code class="computeroutput"><span class="special">&lt;</span></code>
          and returns the smaller value. Any associative binary function or function
          object will work. For instance, to concatenate strings with <code class="computeroutput"><span class="identifier">reduce</span></code> one could use the function object
          <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">plus</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span></code>
          (<code class="computeroutput"><span class="identifier">string_cat</span><span class="special">.</span><span class="identifier">cpp</span></code>):
        </p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">mpi</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">string</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">functional</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">serialization</span><span class="special">/</span><span class="identifier">string</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">namespace</span> <span class="identifier">mpi</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mpi</span><span class="special">;</span>

<span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">argc</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">argv</span><span class="special">[])</span>
<span class="special">{</span>
  <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">environment</span> <span class="identifier">env</span><span class="special">(</span><span class="identifier">argc</span><span class="special">,</span> <span class="identifier">argv</span><span class="special">);</span>
  <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">communicator</span> <span class="identifier">world</span><span class="special">;</span>

  <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">names</span><span class="special">[</span><span class="number">10</span><span class="special">]</span> <span class="special">=</span> <span class="special">{</span> <span class="string">"zero "</span><span class="special">,</span> <span class="string">"one "</span><span class="special">,</span> <span class="string">"two "</span><span class="special">,</span> <span class="string">"three "</span><span class="special">,</span>
                            <span class="string">"four "</span><span class="special">,</span> <span class="string">"five "</span><span class="special">,</span> <span class="string">"six "</span><span class="special">,</span> <span class="string">"seven "</span><span class="special">,</span>
                            <span class="string">"eight "</span><span class="special">,</span> <span class="string">"nine "</span> <span class="special">};</span>

  <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">result</span><span class="special">;</span>
  <span class="identifier">reduce</span><span class="special">(</span><span class="identifier">world</span><span class="special">,</span>
         <span class="identifier">world</span><span class="special">.</span><span class="identifier">rank</span><span class="special">()</span> <span class="special">&lt;</span> <span class="number">10</span><span class="special">?</span> <span class="identifier">names</span><span class="special">[</span><span class="identifier">world</span><span class="special">.</span><span class="identifier">rank</span><span class="special">()]</span>
                          <span class="special">:</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">(</span><span class="string">"many "</span><span class="special">),</span>
         <span class="identifier">result</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">plus</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;(),</span> <span class="number">0</span><span class="special">);</span>

  <span class="keyword">if</span> <span class="special">(</span><span class="identifier">world</span><span class="special">.</span><span class="identifier">rank</span><span class="special">()</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"The result is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">result</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>

  <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
          In this example, we compute a string for each process and then perform
          a reduction that concatenates all of the strings together into one, long
          string. Executing this program with seven processors yields the following
          output:
        </p>
<pre class="programlisting">The result is zero one two three four five six
</pre>
<p>
          Any kind of binary function objects can be used with <code class="computeroutput"><span class="identifier">reduce</span></code>.
          For instance, and there are many such function objects in the C++ standard
          <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">functional</span><span class="special">&gt;</span></code> header and the Boost.MPI header <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">mpi</span><span class="special">/</span><span class="identifier">operations</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></code>. Or, you can create your own function
          object. Function objects used with <code class="computeroutput"><span class="identifier">reduce</span></code>
          must be associative, i.e. <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span>
          <span class="identifier">f</span><span class="special">(</span><span class="identifier">y</span><span class="special">,</span> <span class="identifier">z</span><span class="special">))</span></code> must be equivalent to <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span><span class="identifier">f</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">y</span><span class="special">),</span> <span class="identifier">z</span><span class="special">)</span></code>. If they are also commutative (i..e,
          <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">y</span><span class="special">)</span> <span class="special">==</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">y</span><span class="special">,</span>
          <span class="identifier">x</span><span class="special">)</span></code>),
          Boost.MPI can use a more efficient implementation of <code class="computeroutput"><span class="identifier">reduce</span></code>.
          To state that a function object is commutative, you will need to specialize
          the class <code class="computeroutput"><a class="link" href="../boost/mpi/is_commutative.html" title="Struct template is_commutative">is_commutative</a></code>.
          For instance, we could modify the previous example by telling Boost.MPI
          that string concatenation is commutative:
        </p>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">mpi</span> <span class="special">{</span>

  <span class="keyword">template</span><span class="special">&lt;&gt;</span>
  <span class="keyword">struct</span> <span class="identifier">is_commutative</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">plus</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span>
    <span class="special">:</span> <span class="identifier">mpl</span><span class="special">::</span><span class="identifier">true_</span> <span class="special">{</span> <span class="special">};</span>

<span class="special">}</span> <span class="special">}</span> <span class="comment">// end namespace boost::mpi</span>
</pre>
<p>
          By adding this code prior to <code class="computeroutput"><span class="identifier">main</span><span class="special">()</span></code>, Boost.MPI will assume that string concatenation
          is commutative and employ a different parallel algorithm for the <code class="computeroutput"><span class="identifier">reduce</span></code> operation. Using this algorithm,
          the program outputs the following when run with seven processes:
        </p>
<pre class="programlisting">The result is zero one four five six two three
</pre>
<p>
          Note how the numbers in the resulting string are in a different order:
          this is a direct result of Boost.MPI reordering operations. The result
          in this case differed from the non-commutative result because string concatenation
          is not commutative: <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span><span class="string">"x"</span><span class="special">,</span>
          <span class="string">"y"</span><span class="special">)</span></code>
          is not the same as <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span><span class="string">"y"</span><span class="special">,</span>
          <span class="string">"x"</span><span class="special">)</span></code>,
          because argument order matters. For truly commutative operations (e.g.,
          integer addition), the more efficient commutative algorithm will produce
          the same result as the non-commutative algorithm. Boost.MPI also performs
          direct mappings from function objects in <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">functional</span><span class="special">&gt;</span></code>
          to <code class="computeroutput"><span class="identifier">MPI_Op</span></code> values predefined
          by MPI (e.g., <code class="computeroutput"><span class="identifier">MPI_SUM</span></code>,
          <code class="computeroutput"><span class="identifier">MPI_MAX</span></code>); if you have your
          own function objects that can take advantage of this mapping, see the class
          template <code class="computeroutput"><a class="link" href="../boost/mpi/is_mpi_op.html" title="Struct template is_mpi_op">is_mpi_op</a></code>.
        </p>
<p>
          Like <a class="link" href="tutorial.html#mpi.gather" title="Gather"><code class="computeroutput"><span class="identifier">gather</span></code></a>,
          <code class="computeroutput"><span class="identifier">reduce</span></code> has an "all"
          variant called <code class="computeroutput"><a class="link" href="../boost/mpi/all_reduce.html" title="Function all_reduce">all_reduce</a></code> that performs
          the reduction operation and broadcasts the result to all processes. This
          variant is useful, for instance, in establishing global minimum or maximum
          values.
        </p>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="mpi.communicators"></a>Managing communicators</h3></div></div></div>
<p>
        Communication with Boost.MPI always occurs over a communicator. A communicator
        contains a set of processes that can send messages among themselves and perform
        collective operations. There can be many communicators within a single program,
        each of which contains its own isolated communication space that acts independently
        of the other communicators.
      </p>
<p>
        When the MPI environment is initialized, only the "world" communicator
        (called <code class="computeroutput"><span class="identifier">MPI_COMM_WORLD</span></code> in
        the MPI C and Fortran bindings) is available. The "world" communicator,
        accessed by default-constructing a <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html" title="Class communicator">mpi::communicator</a></code>
        object, contains all of the MPI processes present when the program begins
        execution. Other communicators can then be constructed by duplicating or
        building subsets of the "world" communicator. For instance, in
        the following program we split the processes into two groups: one for processes
        generating data and the other for processes that will collect the data. (<code class="computeroutput"><span class="identifier">generate_collect</span><span class="special">.</span><span class="identifier">cpp</span></code>)
      </p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">mpi</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cstdlib</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">serialization</span><span class="special">/</span><span class="identifier">vector</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">namespace</span> <span class="identifier">mpi</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mpi</span><span class="special">;</span>

<span class="keyword">enum</span> <span class="identifier">message_tags</span> <span class="special">{</span><span class="identifier">msg_data_packet</span><span class="special">,</span> <span class="identifier">msg_broadcast_data</span><span class="special">,</span> <span class="identifier">msg_finished</span><span class="special">};</span>

<span class="keyword">void</span> <span class="identifier">generate_data</span><span class="special">(</span><span class="identifier">mpi</span><span class="special">::</span><span class="identifier">communicator</span> <span class="identifier">local</span><span class="special">,</span> <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">communicator</span> <span class="identifier">world</span><span class="special">);</span>
<span class="keyword">void</span> <span class="identifier">collect_data</span><span class="special">(</span><span class="identifier">mpi</span><span class="special">::</span><span class="identifier">communicator</span> <span class="identifier">local</span><span class="special">,</span> <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">communicator</span> <span class="identifier">world</span><span class="special">);</span>

<span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">argc</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">argv</span><span class="special">[])</span>
<span class="special">{</span>
  <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">environment</span> <span class="identifier">env</span><span class="special">(</span><span class="identifier">argc</span><span class="special">,</span> <span class="identifier">argv</span><span class="special">);</span>
  <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">communicator</span> <span class="identifier">world</span><span class="special">;</span>

  <span class="keyword">bool</span> <span class="identifier">is_generator</span> <span class="special">=</span> <span class="identifier">world</span><span class="special">.</span><span class="identifier">rank</span><span class="special">()</span> <span class="special">&lt;</span> <span class="number">2</span> <span class="special">*</span> <span class="identifier">world</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">/</span> <span class="number">3</span><span class="special">;</span>
  <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">communicator</span> <span class="identifier">local</span> <span class="special">=</span> <span class="identifier">world</span><span class="special">.</span><span class="identifier">split</span><span class="special">(</span><span class="identifier">is_generator</span><span class="special">?</span> <span class="number">0</span> <span class="special">:</span> <span class="number">1</span><span class="special">);</span>
  <span class="keyword">if</span> <span class="special">(</span><span class="identifier">is_generator</span><span class="special">)</span> <span class="identifier">generate_data</span><span class="special">(</span><span class="identifier">local</span><span class="special">,</span> <span class="identifier">world</span><span class="special">);</span>
  <span class="keyword">else</span> <span class="identifier">collect_data</span><span class="special">(</span><span class="identifier">local</span><span class="special">,</span> <span class="identifier">world</span><span class="special">);</span>

  <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
        When communicators are split in this way, their processes retain membership
        in both the original communicator (which is not altered by the split) and
        the new communicator. However, the ranks of the processes may be different
        from one communicator to the next, because the rank values within a communicator
        are always contiguous values starting at zero. In the example above, the
        first two thirds of the processes become "generators" and the remaining
        processes become "collectors". The ranks of the "collectors"
        in the <code class="computeroutput"><span class="identifier">world</span></code> communicator
        will be 2/3 <code class="computeroutput"><span class="identifier">world</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span></code>
        and greater, whereas the ranks of the same collector processes in the <code class="computeroutput"><span class="identifier">local</span></code> communicator will start at zero.
        The following excerpt from <code class="computeroutput"><span class="identifier">collect_data</span><span class="special">()</span></code> (in <code class="computeroutput"><span class="identifier">generate_collect</span><span class="special">.</span><span class="identifier">cpp</span></code>) illustrates
        how to manage multiple communicators:
      </p>
<pre class="programlisting"><span class="identifier">mpi</span><span class="special">::</span><span class="identifier">status</span> <span class="identifier">msg</span> <span class="special">=</span> <span class="identifier">world</span><span class="special">.</span><span class="identifier">probe</span><span class="special">();</span>
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">msg</span><span class="special">.</span><span class="identifier">tag</span><span class="special">()</span> <span class="special">==</span> <span class="identifier">msg_data_packet</span><span class="special">)</span> <span class="special">{</span>
  <span class="comment">// Receive the packet of data</span>
  <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">data</span><span class="special">;</span>
  <span class="identifier">world</span><span class="special">.</span><span class="identifier">recv</span><span class="special">(</span><span class="identifier">msg</span><span class="special">.</span><span class="identifier">source</span><span class="special">(),</span> <span class="identifier">msg</span><span class="special">.</span><span class="identifier">tag</span><span class="special">(),</span> <span class="identifier">data</span><span class="special">);</span>

  <span class="comment">// Tell each of the collectors that we'll be broadcasting some data</span>
  <span class="keyword">for</span> <span class="special">(</span><span class="keyword">int</span> <span class="identifier">dest</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span> <span class="identifier">dest</span> <span class="special">&lt;</span> <span class="identifier">local</span><span class="special">.</span><span class="identifier">size</span><span class="special">();</span> <span class="special">++</span><span class="identifier">dest</span><span class="special">)</span>
    <span class="identifier">local</span><span class="special">.</span><span class="identifier">send</span><span class="special">(</span><span class="identifier">dest</span><span class="special">,</span> <span class="identifier">msg_broadcast_data</span><span class="special">,</span> <span class="identifier">msg</span><span class="special">.</span><span class="identifier">source</span><span class="special">());</span>

  <span class="comment">// Broadcast the actual data.</span>
  <span class="identifier">broadcast</span><span class="special">(</span><span class="identifier">local</span><span class="special">,</span> <span class="identifier">data</span><span class="special">,</span> <span class="number">0</span><span class="special">);</span>
<span class="special">}</span>
</pre>
<p>
        The code in this except is executed by the "master" collector,
        e.g., the node with rank 2/3 <code class="computeroutput"><span class="identifier">world</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span></code>
        in the <code class="computeroutput"><span class="identifier">world</span></code> communicator
        and rank 0 in the <code class="computeroutput"><span class="identifier">local</span></code> (collector)
        communicator. It receives a message from a generator via the <code class="computeroutput"><span class="identifier">world</span></code> communicator, then broadcasts the
        message to each of the collectors via the <code class="computeroutput"><span class="identifier">local</span></code>
        communicator.
      </p>
<p>
        For more control in the creation of communicators for subgroups of processes,
        the Boost.MPI <code class="computeroutput"><a class="link" href="../boost/mpi/group.html" title="Class group">group</a></code>
        provides facilities to compute the union (<code class="computeroutput"><span class="special">|</span></code>),
        intersection (<code class="computeroutput"><span class="special">&amp;</span></code>), and difference
        (<code class="computeroutput"><span class="special">-</span></code>) of two groups, generate
        arbitrary subgroups, etc.
      </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="mpi.skeleton_and_content"></a>Separating structure from content</h3></div></div></div>
<p>
        When communicating data types over MPI that are not fundamental to MPI (such
        as strings, lists, and user-defined data types), Boost.MPI must first serialize
        these data types into a buffer and then communicate them; the receiver then
        copies the results into a buffer before deserializing into an object on the
        other end. For some data types, this overhead can be eliminated by using
        <code class="computeroutput"><a class="link" href="../boost/mpi/is_mpi_datatype.html" title="Struct template is_mpi_datatype">is_mpi_datatype</a></code>.
        However, variable-length data types such as strings and lists cannot be MPI
        data types.
      </p>
<p>
        Boost.MPI supports a second technique for improving performance by separating
        the structure of these variable-length data structures from the content stored
        in the data structures. This feature is only beneficial when the shape of
        the data structure remains the same but the content of the data structure
        will need to be communicated several times. For instance, in a finite element
        analysis the structure of the mesh may be fixed at the beginning of computation
        but the various variables on the cells of the mesh (temperature, stress,
        etc.) will be communicated many times within the iterative analysis process.
        In this case, Boost.MPI allows one to first send the "skeleton"
        of the mesh once, then transmit the "content" multiple times. Since
        the content need not contain any information about the structure of the data
        type, it can be transmitted without creating separate communication buffers.
      </p>
<p>
        To illustrate the use of skeletons and content, we will take a somewhat more
        limited example wherein a master process generates random number sequences
        into a list and transmits them to several slave processes. The length of
        the list will be fixed at program startup, so the content of the list (i.e.,
        the current sequence of numbers) can be transmitted efficiently. The complete
        example is available in <code class="computeroutput"><span class="identifier">example</span><span class="special">/</span><span class="identifier">random_content</span><span class="special">.</span><span class="identifier">cpp</span></code>. We
        being with the master process (rank 0), which builds a list, communicates
        its structure via a <code class="computeroutput"><a class="link" href="../boost/mpi/skeleton.html" title="Function template skeleton">skeleton</a></code>, then repeatedly
        generates random number sequences to be broadcast to the slave processes
        via <code class="computeroutput"><a class="link" href="../boost/mpi/content.html" title="Class content">content</a></code>:
      </p>
<pre class="programlisting"><span class="comment">// Generate the list and broadcast its structure</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">l</span><span class="special">(</span><span class="identifier">list_len</span><span class="special">);</span>
<span class="identifier">broadcast</span><span class="special">(</span><span class="identifier">world</span><span class="special">,</span> <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">skeleton</span><span class="special">(</span><span class="identifier">l</span><span class="special">),</span> <span class="number">0</span><span class="special">);</span>

<span class="comment">// Generate content several times and broadcast out that content</span>
<span class="identifier">mpi</span><span class="special">::</span><span class="identifier">content</span> <span class="identifier">c</span> <span class="special">=</span> <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">get_content</span><span class="special">(</span><span class="identifier">l</span><span class="special">);</span>
<span class="keyword">for</span> <span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="identifier">iterations</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span> <span class="special">{</span>
  <span class="comment">// Generate new random values</span>
  <span class="identifier">std</span><span class="special">::</span><span class="identifier">generate</span><span class="special">(</span><span class="identifier">l</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">l</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="special">&amp;</span><span class="identifier">random</span><span class="special">);</span>

  <span class="comment">// Broadcast the new content of l</span>
  <span class="identifier">broadcast</span><span class="special">(</span><span class="identifier">world</span><span class="special">,</span> <span class="identifier">c</span><span class="special">,</span> <span class="number">0</span><span class="special">);</span>
<span class="special">}</span>

<span class="comment">// Notify the slaves that we're done by sending all zeroes</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">fill</span><span class="special">(</span><span class="identifier">l</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">l</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="number">0</span><span class="special">);</span>
<span class="identifier">broadcast</span><span class="special">(</span><span class="identifier">world</span><span class="special">,</span> <span class="identifier">c</span><span class="special">,</span> <span class="number">0</span><span class="special">);</span>
</pre>
<p>
        The slave processes have a very similar structure to the master. They receive
        (via the <code class="computeroutput"><a class="link" href="../boost/mpi/broadcast.html" title="Function broadcast">broadcast()</a></code> call) the skeleton of the
        data structure, then use it to build their own lists of integers. In each
        iteration, they receive via another <code class="computeroutput"><span class="identifier">broadcast</span><span class="special">()</span></code> the new content in the data structure and
        compute some property of the data:
      </p>
<pre class="programlisting"><span class="comment">// Receive the content and build up our own list</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">l</span><span class="special">;</span>
<span class="identifier">broadcast</span><span class="special">(</span><span class="identifier">world</span><span class="special">,</span> <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">skeleton</span><span class="special">(</span><span class="identifier">l</span><span class="special">),</span> <span class="number">0</span><span class="special">);</span>

<span class="identifier">mpi</span><span class="special">::</span><span class="identifier">content</span> <span class="identifier">c</span> <span class="special">=</span> <span class="identifier">mpi</span><span class="special">::</span><span class="identifier">get_content</span><span class="special">(</span><span class="identifier">l</span><span class="special">);</span>
<span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
<span class="keyword">do</span> <span class="special">{</span>
  <span class="identifier">broadcast</span><span class="special">(</span><span class="identifier">world</span><span class="special">,</span> <span class="identifier">c</span><span class="special">,</span> <span class="number">0</span><span class="special">);</span>

  <span class="keyword">if</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">find_if</span>
       <span class="special">(</span><span class="identifier">l</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">l</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span>
        <span class="identifier">std</span><span class="special">::</span><span class="identifier">bind1st</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">not_equal_to</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(),</span> <span class="number">0</span><span class="special">))</span> <span class="special">==</span> <span class="identifier">l</span><span class="special">.</span><span class="identifier">end</span><span class="special">())</span>
    <span class="keyword">break</span><span class="special">;</span>

  <span class="comment">// Compute some property of the data.</span>

  <span class="special">++</span><span class="identifier">i</span><span class="special">;</span>
<span class="special">}</span> <span class="keyword">while</span> <span class="special">(</span><span class="keyword">true</span><span class="special">);</span>
</pre>
<p>
        The skeletons and content of any Serializable data type can be transmitted
        either via the <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp43887088-bb">send</a></code> and <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp44013376-bb">recv</a></code> members of the <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html" title="Class communicator">communicator</a></code>
        class (for point-to-point communicators) or broadcast via the <code class="computeroutput"><a class="link" href="../boost/mpi/broadcast.html" title="Function broadcast">broadcast()</a></code> collective. When separating
        a data structure into a skeleton and content, be careful not to modify the
        data structure (either on the sender side or the receiver side) without transmitting
        the skeleton again. Boost.MPI can not detect these accidental modifications
        to the data structure, which will likely result in incorrect data being transmitted
        or unstable programs.
      </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="mpi.performance_optimizations"></a>Performance optimizations</h3></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="tutorial.html#mpi.serialization_optimizations">Serialization optimizations</a></span></dt>
<dt><span class="section"><a href="tutorial.html#mpi.homogeneous_machines">Homogeneous machines</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="mpi.serialization_optimizations"></a>Serialization optimizations</h4></div></div></div>
<p>
          To obtain optimal performance for small fixed-length data types not containing
          any pointers it is very important to mark them using the type traits of
          Boost.MPI and Boost.Serialization.
        </p>
<p>
          It was alredy discussed that fixed length types containing no pointers
          can be using as <code class="computeroutput"><a class="link" href="../boost/mpi/is_mpi_datatype.html" title="Struct template is_mpi_datatype">is_mpi_datatype</a></code>, e.g.:
        </p>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">mpi</span> <span class="special">{</span>
  <span class="keyword">template</span> <span class="special">&lt;&gt;</span>
  <span class="keyword">struct</span> <span class="identifier">is_mpi_datatype</span><span class="special">&lt;</span><span class="identifier">gps_position</span><span class="special">&gt;</span> <span class="special">:</span> <span class="identifier">mpl</span><span class="special">::</span><span class="identifier">true_</span> <span class="special">{</span> <span class="special">};</span>
<span class="special">}</span> <span class="special">}</span>
</pre>
<p>
          or the equivalent macro
        </p>
<pre class="programlisting"><span class="identifier">BOOST_IS_MPI_DATATYPE</span><span class="special">(</span><span class="identifier">gps_position</span><span class="special">)</span>
</pre>
<p>
          In addition it can give a substantial performance gain to turn off tracking
          and versioning for these types, if no pointers to these types are used,
          by using the traits classes or helper macros of Boost.Serialization:
        </p>
<pre class="programlisting"><span class="identifier">BOOST_CLASS_TRACKING</span><span class="special">(</span><span class="identifier">gps_position</span><span class="special">,</span><span class="identifier">track_never</span><span class="special">)</span>
<span class="identifier">BOOST_CLASS_IMPLEMENTATION</span><span class="special">(</span><span class="identifier">gps_position</span><span class="special">,</span><span class="identifier">object_serializable</span><span class="special">)</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="mpi.homogeneous_machines"></a>Homogeneous machines</h4></div></div></div>
<p>
          More optimizations are possible on homogeneous machines, by avoiding MPI_Pack/MPI_Unpack
          calls but using direct bitwise copy. This feature can be enabled by defining
          the macro BOOST_MPI_HOMOGENEOUS when building Boost.MPI and when building
          the application.
        </p>
<p>
          In addition all classes need to be marked both as is_mpi_datatype and as
          is_bitwise_serializable, by using the helper macro of Boost.Serialization:
        </p>
<pre class="programlisting"><span class="identifier">BOOST_IS_BITWISE_SERIALIZABLE</span><span class="special">(</span><span class="identifier">gps_position</span><span class="special">)</span>
</pre>
<p>
          Usually it is safe to serialize a class for which is_mpi_datatype is true
          by using binary copy of the bits. The exception are classes for which some
          members should be skipped for serialization.
        </p>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="mpi.c_mapping"></a>Mapping from C MPI to Boost.MPI</h3></div></div></div>
<p>
        This section provides tables that map from the functions and constants of
        the standard C MPI to their Boost.MPI equivalents. It will be most useful
        for users that are already familiar with the C or Fortran interfaces to MPI,
        or for porting existing parallel programs to Boost.MPI.
      </p>
<div class="table">
<a name="mpi.tutorial.c_mapping.t0"></a><p class="title"><b>Table&#160;19.1.&#160;Point-to-point communication</b></p>
<div class="table-contents"><table class="table" summary="Point-to-point communication">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  C Function/Constant
                </p>
              </th>
<th>
                <p>
                  Boost.MPI Equivalent
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_ANY_SOURCE</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">any_source</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_ANY_TAG</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">any_tag</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node40.html#Node40" target="_top"><code class="computeroutput"><span class="identifier">MPI_Bsend</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node51.html#Node51" target="_top"><code class="computeroutput"><span class="identifier">MPI_Bsend_init</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node42.html#Node42" target="_top"><code class="computeroutput"><span class="identifier">MPI_Buffer_attach</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node42.html#Node42" target="_top"><code class="computeroutput"><span class="identifier">MPI_Buffer_detach</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node50.html#Node50" target="_top"><code class="computeroutput"><span class="identifier">MPI_Cancel</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/request.html#idp44206080-bb">request::cancel</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node35.html#Node35" target="_top"><code class="computeroutput"><span class="identifier">MPI_Get_count</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/status.html#idp44585712-bb">status::count</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node46.html#Node46" target="_top"><code class="computeroutput"><span class="identifier">MPI_Ibsend</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node50.html#Node50" target="_top"><code class="computeroutput"><span class="identifier">MPI_Iprobe</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp44083696-bb">communicator::iprobe</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node46.html#Node46" target="_top"><code class="computeroutput"><span class="identifier">MPI_Irsend</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node46.html#Node46" target="_top"><code class="computeroutput"><span class="identifier">MPI_Isend</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp44039536-bb">communicator::isend</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node46.html#Node46" target="_top"><code class="computeroutput"><span class="identifier">MPI_Issend</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node46.html#Node46" target="_top"><code class="computeroutput"><span class="identifier">MPI_Irecv</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp44039536-bb">communicator::irecv</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node50.html#Node50" target="_top"><code class="computeroutput"><span class="identifier">MPI_Probe</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp44079248-bb">communicator::probe</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node53.html#Node53" target="_top"><code class="computeroutput"><span class="identifier">MPI_PROC_NULL</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node34.html#Node34" target="_top"><code class="computeroutput"><span class="identifier">MPI_Recv</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp44013376-bb">communicator::recv</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node51.html#Node51" target="_top"><code class="computeroutput"><span class="identifier">MPI_Recv_init</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node47.html#Node47" target="_top"><code class="computeroutput"><span class="identifier">MPI_Request_free</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node40.html#Node40" target="_top"><code class="computeroutput"><span class="identifier">MPI_Rsend</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node51.html#Node51" target="_top"><code class="computeroutput"><span class="identifier">MPI_Rsend_init</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node31.html#Node31" target="_top"><code class="computeroutput"><span class="identifier">MPI_Send</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp43887088-bb">communicator::send</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node52.html#Node52" target="_top"><code class="computeroutput"><span class="identifier">MPI_Sendrecv</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node52.html#Node52" target="_top"><code class="computeroutput"><span class="identifier">MPI_Sendrecv_replace</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node51.html#Node51" target="_top"><code class="computeroutput"><span class="identifier">MPI_Send_init</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node40.html#Node40" target="_top"><code class="computeroutput"><span class="identifier">MPI_Ssend</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node51.html#Node51" target="_top"><code class="computeroutput"><span class="identifier">MPI_Ssend_init</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node51.html#Node51" target="_top"><code class="computeroutput"><span class="identifier">MPI_Start</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node51.html#Node51" target="_top"><code class="computeroutput"><span class="identifier">MPI_Startall</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node47.html#Node47" target="_top"><code class="computeroutput"><span class="identifier">MPI_Test</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/request.html#idp44202704-bb">request::test</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node47.html#Node47" target="_top"><code class="computeroutput"><span class="identifier">MPI_Testall</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/test_all.html" title="Function test_all">test_all</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node47.html#Node47" target="_top"><code class="computeroutput"><span class="identifier">MPI_Testany</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/test_any.html" title="Function template test_any">test_any</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node47.html#Node47" target="_top"><code class="computeroutput"><span class="identifier">MPI_Testsome</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/test_some.html" title="Function test_some">test_some</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node50.html#Node50" target="_top"><code class="computeroutput"><span class="identifier">MPI_Test_cancelled</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/status.html#idp44584944-bb">status::cancelled</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node47.html#Node47" target="_top"><code class="computeroutput"><span class="identifier">MPI_Wait</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/request.html#idp44202704-bb">request::wait</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node47.html#Node47" target="_top"><code class="computeroutput"><span class="identifier">MPI_Waitall</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/wait_all.html" title="Function wait_all">wait_all</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node47.html#Node47" target="_top"><code class="computeroutput"><span class="identifier">MPI_Waitany</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/wait_any.html" title="Function template wait_any">wait_any</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node47.html#Node47" target="_top"><code class="computeroutput"><span class="identifier">MPI_Waitsome</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/wait_some.html" title="Function wait_some">wait_some</a></code>
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
        Boost.MPI automatically maps C and C++ data types to their MPI equivalents.
        The following table illustrates the mappings between C++ types and MPI datatype
        constants.
      </p>
<div class="table">
<a name="mpi.tutorial.c_mapping.t1"></a><p class="title"><b>Table&#160;19.2.&#160;Datatypes</b></p>
<div class="table-contents"><table class="table" summary="Datatypes">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  C Constant
                </p>
              </th>
<th>
                <p>
                  Boost.MPI Equivalent
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_CHAR</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="keyword">signed</span> <span class="keyword">char</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_SHORT</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="keyword">signed</span> <span class="keyword">short</span>
                  <span class="keyword">int</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_INT</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="keyword">signed</span> <span class="keyword">int</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_LONG</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="keyword">signed</span> <span class="keyword">long</span>
                  <span class="keyword">int</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_UNSIGNED_CHAR</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="keyword">unsigned</span> <span class="keyword">char</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_UNSIGNED_SHORT</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="keyword">unsigned</span> <span class="keyword">short</span>
                  <span class="keyword">int</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_UNSIGNED_INT</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="keyword">unsigned</span> <span class="keyword">int</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_UNSIGNED_LONG</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="keyword">unsigned</span> <span class="keyword">long</span>
                  <span class="keyword">int</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_FLOAT</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="keyword">float</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_DOUBLE</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="keyword">double</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_LONG_DOUBLE</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_BYTE</span></code>
                </p>
              </td>
<td>
                <p>
                  unused
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_PACKED</span></code>
                </p>
              </td>
<td>
                <p>
                  used internally for <a class="link" href="tutorial.html#mpi.user_data_types" title="User-defined data types">serialized
                  data types</a>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_LONG_LONG_INT</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">long</span>
                  <span class="keyword">int</span></code>, if supported by compiler
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_UNSIGNED_LONG_LONG_INT</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="keyword">unsigned</span> <span class="keyword">long</span>
                  <span class="keyword">long</span> <span class="keyword">int</span></code>,
                  if supported by compiler
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_FLOAT_INT</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">,</span>
                  <span class="keyword">int</span><span class="special">&gt;</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_DOUBLE_INT</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">,</span>
                  <span class="keyword">int</span><span class="special">&gt;</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_LONG_INT</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="keyword">long</span><span class="special">,</span>
                  <span class="keyword">int</span><span class="special">&gt;</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_2INT</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">int</span><span class="special">&gt;</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_SHORT_INT</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="keyword">short</span><span class="special">,</span>
                  <span class="keyword">int</span><span class="special">&gt;</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_LONG_DOUBLE_INT</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="keyword">long</span> <span class="keyword">double</span><span class="special">,</span> <span class="keyword">int</span><span class="special">&gt;</span></code>
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
        Boost.MPI does not provide direct wrappers to the MPI derived datatypes functionality.
        Instead, Boost.MPI relies on the <a href="http://www.boost.org/libs/serialization/doc" target="_top">Boost.Serialization</a>
        library to construct MPI datatypes for user-defined classe. The section on
        <a class="link" href="tutorial.html#mpi.user_data_types" title="User-defined data types">user-defined data types</a> describes
        this mechanism, which is used for types that marked as "MPI datatypes"
        using <code class="computeroutput"><a class="link" href="../boost/mpi/is_mpi_datatype.html" title="Struct template is_mpi_datatype">is_mpi_datatype</a></code>.
      </p>
<p>
        The derived datatypes table that follows describes which C++ types correspond
        to the functionality of the C MPI's datatype constructor. Boost.MPI may not
        actually use the C MPI function listed when building datatypes of a certain
        form. Since the actual datatypes built by Boost.MPI are typically hidden
        from the user, many of these operations are called internally by Boost.MPI.
      </p>
<div class="table">
<a name="mpi.tutorial.c_mapping.t2"></a><p class="title"><b>Table&#160;19.3.&#160;Derived datatypes</b></p>
<div class="table-contents"><table class="table" summary="Derived datatypes">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  C Function/Constant
                </p>
              </th>
<th>
                <p>
                  Boost.MPI Equivalent
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node56.html#Node56" target="_top"><code class="computeroutput"><span class="identifier">MPI_Address</span></code></a>
                </p>
              </td>
<td>
                <p>
                  used automatically in Boost.MPI
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node58.html#Node58" target="_top"><code class="computeroutput"><span class="identifier">MPI_Type_commit</span></code></a>
                </p>
              </td>
<td>
                <p>
                  used automatically in Boost.MPI
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node55.html#Node55" target="_top"><code class="computeroutput"><span class="identifier">MPI_Type_contiguous</span></code></a>
                </p>
              </td>
<td>
                <p>
                  arrays
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node56.html#Node56" target="_top"><code class="computeroutput"><span class="identifier">MPI_Type_extent</span></code></a>
                </p>
              </td>
<td>
                <p>
                  used automatically in Boost.MPI
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node58.html#Node58" target="_top"><code class="computeroutput"><span class="identifier">MPI_Type_free</span></code></a>
                </p>
              </td>
<td>
                <p>
                  used automatically in Boost.MPI
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node55.html#Node55" target="_top"><code class="computeroutput"><span class="identifier">MPI_Type_hindexed</span></code></a>
                </p>
              </td>
<td>
                <p>
                  any type used as a subobject
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node55.html#Node55" target="_top"><code class="computeroutput"><span class="identifier">MPI_Type_hvector</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unused
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node55.html#Node55" target="_top"><code class="computeroutput"><span class="identifier">MPI_Type_indexed</span></code></a>
                </p>
              </td>
<td>
                <p>
                  any type used as a subobject
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node57.html#Node57" target="_top"><code class="computeroutput"><span class="identifier">MPI_Type_lb</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node56.html#Node56" target="_top"><code class="computeroutput"><span class="identifier">MPI_Type_size</span></code></a>
                </p>
              </td>
<td>
                <p>
                  used automatically in Boost.MPI
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node55.html#Node55" target="_top"><code class="computeroutput"><span class="identifier">MPI_Type_struct</span></code></a>
                </p>
              </td>
<td>
                <p>
                  user-defined classes and structs
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node57.html#Node57" target="_top"><code class="computeroutput"><span class="identifier">MPI_Type_ub</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node55.html#Node55" target="_top"><code class="computeroutput"><span class="identifier">MPI_Type_vector</span></code></a>
                </p>
              </td>
<td>
                <p>
                  used automatically in Boost.MPI
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
        MPI's packing facilities store values into a contiguous buffer, which can
        later be transmitted via MPI and unpacked into separate values via MPI's
        unpacking facilities. As with datatypes, Boost.MPI provides an abstract interface
        to MPI's packing and unpacking facilities. In particular, the two archive
        classes <code class="computeroutput"><a class="link" href="../boost/mpi/packed_oarchive.html" title="Class packed_oarchive">packed_oarchive</a></code>
        and <code class="computeroutput"><a class="link" href="../boost/mpi/packed_iarchive.html" title="Class packed_iarchive">packed_iarchive</a></code>
        can be used to pack or unpack a contiguous buffer using MPI's facilities.
      </p>
<div class="table">
<a name="mpi.tutorial.c_mapping.t3"></a><p class="title"><b>Table&#160;19.4.&#160;Packing and unpacking</b></p>
<div class="table-contents"><table class="table" summary="Packing and unpacking">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  C Function
                </p>
              </th>
<th>
                <p>
                  Boost.MPI Equivalent
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node62.html#Node62" target="_top"><code class="computeroutput"><span class="identifier">MPI_Pack</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/packed_oarchive.html" title="Class packed_oarchive">packed_oarchive</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node62.html#Node62" target="_top"><code class="computeroutput"><span class="identifier">MPI_Pack_size</span></code></a>
                </p>
              </td>
<td>
                <p>
                  used internally by Boost.MPI
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node62.html#Node62" target="_top"><code class="computeroutput"><span class="identifier">MPI_Unpack</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/packed_iarchive.html" title="Class packed_iarchive">packed_iarchive</a></code>
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
        Boost.MPI supports a one-to-one mapping for most of the MPI collectives.
        For each collective provided by Boost.MPI, the underlying C MPI collective
        will be invoked when it is possible (and efficient) to do so.
      </p>
<div class="table">
<a name="mpi.tutorial.c_mapping.t4"></a><p class="title"><b>Table&#160;19.5.&#160;Collectives</b></p>
<div class="table-contents"><table class="table" summary="Collectives">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  C Function
                </p>
              </th>
<th>
                <p>
                  Boost.MPI Equivalent
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node73.html#Node73" target="_top"><code class="computeroutput"><span class="identifier">MPI_Allgather</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/all_gather.html" title="Function all_gather">all_gather</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node73.html#Node73" target="_top"><code class="computeroutput"><span class="identifier">MPI_Allgatherv</span></code></a>
                </p>
              </td>
<td>
                <p>
                  most uses supported by <code class="computeroutput"><a class="link" href="../boost/mpi/all_gather.html" title="Function all_gather">all_gather</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node82.html#Node82" target="_top"><code class="computeroutput"><span class="identifier">MPI_Allreduce</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/all_reduce.html" title="Function all_reduce">all_reduce</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node75.html#Node75" target="_top"><code class="computeroutput"><span class="identifier">MPI_Alltoall</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/all_to_all.html" title="Function all_to_all">all_to_all</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node75.html#Node75" target="_top"><code class="computeroutput"><span class="identifier">MPI_Alltoallv</span></code></a>
                </p>
              </td>
<td>
                <p>
                  most uses supported by <code class="computeroutput"><a class="link" href="../boost/mpi/all_to_all.html" title="Function all_to_all">all_to_all</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node66.html#Node66" target="_top"><code class="computeroutput"><span class="identifier">MPI_Barrier</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp44118048-bb">communicator::barrier</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node67.html#Node67" target="_top"><code class="computeroutput"><span class="identifier">MPI_Bcast</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/broadcast.html" title="Function broadcast">broadcast</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node69.html#Node69" target="_top"><code class="computeroutput"><span class="identifier">MPI_Gather</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/gather.html" title="Function gather">gather</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node69.html#Node69" target="_top"><code class="computeroutput"><span class="identifier">MPI_Gatherv</span></code></a>
                </p>
              </td>
<td>
                <p>
                  most uses supported by <code class="computeroutput"><a class="link" href="../boost/mpi/gather.html" title="Function gather">gather</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node77.html#Node77" target="_top"><code class="computeroutput"><span class="identifier">MPI_Reduce</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/reduce.html" title="Function reduce">reduce</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node83.html#Node83" target="_top"><code class="computeroutput"><span class="identifier">MPI_Reduce_scatter</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node84.html#Node84" target="_top"><code class="computeroutput"><span class="identifier">MPI_Scan</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/scan.html" title="Function scan">scan</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node71.html#Node71" target="_top"><code class="computeroutput"><span class="identifier">MPI_Scatter</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/scatter.html" title="Function scatter">scatter</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node71.html#Node71" target="_top"><code class="computeroutput"><span class="identifier">MPI_Scatterv</span></code></a>
                </p>
              </td>
<td>
                <p>
                  most uses supported by <code class="computeroutput"><a class="link" href="../boost/mpi/scatter.html" title="Function scatter">scatter</a></code>
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
        Boost.MPI uses function objects to specify how reductions should occur in
        its equivalents to <code class="computeroutput"><span class="identifier">MPI_Allreduce</span></code>,
        <code class="computeroutput"><span class="identifier">MPI_Reduce</span></code>, and <code class="computeroutput"><span class="identifier">MPI_Scan</span></code>. The following table illustrates
        how <a href="http://www.mpi-forum.org/docs/mpi-11-html/node78.html#Node78" target="_top">predefined</a>
        and <a href="http://www.mpi-forum.org/docs/mpi-11-html/node80.html#Node80" target="_top">user-defined</a>
        reduction operations can be mapped between the C MPI and Boost.MPI.
      </p>
<div class="table">
<a name="mpi.tutorial.c_mapping.t5"></a><p class="title"><b>Table&#160;19.6.&#160;Reduction operations</b></p>
<div class="table-contents"><table class="table" summary="Reduction operations">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  C Constant
                </p>
              </th>
<th>
                <p>
                  Boost.MPI Equivalent
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_BAND</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/bitwise_and.html" title="Struct template bitwise_and">bitwise_and</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_BOR</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/bitwise_or.html" title="Struct template bitwise_or">bitwise_or</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_BXOR</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/bitwise_xor.html" title="Struct template bitwise_xor">bitwise_xor</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_LAND</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">logical_and</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_LOR</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">logical_or</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_LXOR</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/logical_xor.html" title="Struct template logical_xor">logical_xor</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_MAX</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/maximum.html" title="Struct template maximum">maximum</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_MAXLOC</span></code>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_MIN</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/minimum.html" title="Struct template minimum">minimum</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_MINLOC</span></code>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_Op_create</span></code>
                </p>
              </td>
<td>
                <p>
                  used internally by Boost.MPI
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_Op_free</span></code>
                </p>
              </td>
<td>
                <p>
                  used internally by Boost.MPI
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_PROD</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">multiplies</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_SUM</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">plus</span></code>
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
        MPI defines several special communicators, including <code class="computeroutput"><span class="identifier">MPI_COMM_WORLD</span></code>
        (including all processes that the local process can communicate with), <code class="computeroutput"><span class="identifier">MPI_COMM_SELF</span></code> (including only the local
        process), and <code class="computeroutput"><span class="identifier">MPI_COMM_EMPTY</span></code>
        (including no processes). These special communicators are all instances of
        the <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html" title="Class communicator">communicator</a></code>
        class in Boost.MPI.
      </p>
<div class="table">
<a name="mpi.tutorial.c_mapping.t6"></a><p class="title"><b>Table&#160;19.7.&#160;Predefined communicators</b></p>
<div class="table-contents"><table class="table" summary="Predefined communicators">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  C Constant
                </p>
              </th>
<th>
                <p>
                  Boost.MPI Equivalent
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_COMM_WORLD</span></code>
                </p>
              </td>
<td>
                <p>
                  a default-constructed <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html" title="Class communicator">communicator</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_COMM_SELF</span></code>
                </p>
              </td>
<td>
                <p>
                  a <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html" title="Class communicator">communicator</a></code>
                  that contains only the current process
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_COMM_EMPTY</span></code>
                </p>
              </td>
<td>
                <p>
                  a <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html" title="Class communicator">communicator</a></code>
                  that evaluates false
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
        Boost.MPI supports groups of processes through its <code class="computeroutput"><a class="link" href="../boost/mpi/group.html" title="Class group">group</a></code> class.
      </p>
<div class="table">
<a name="mpi.tutorial.c_mapping.t7"></a><p class="title"><b>Table&#160;19.8.&#160;Group operations and constants</b></p>
<div class="table-contents"><table class="table" summary="Group operations and constants">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  C Function/Constant
                </p>
              </th>
<th>
                <p>
                  Boost.MPI Equivalent
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_GROUP_EMPTY</span></code>
                </p>
              </td>
<td>
                <p>
                  a default-constructed <code class="computeroutput"><a class="link" href="../boost/mpi/group.html" title="Class group">group</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node97.html#Node97" target="_top"><code class="computeroutput"><span class="identifier">MPI_Group_size</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/group.html#idp44296768-bb">group::size</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node97.html#Node97" target="_top"><code class="computeroutput"><span class="identifier">MPI_Group_rank</span></code></a>
                </p>
              </td>
<td>
                <p>
                  memberref boost::mpi::group::rank <code class="computeroutput"><span class="identifier">group</span><span class="special">::</span><span class="identifier">rank</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node97.html#Node97" target="_top"><code class="computeroutput"><span class="identifier">MPI_Group_translate_ranks</span></code></a>
                </p>
              </td>
<td>
                <p>
                  memberref boost::mpi::group::translate_ranks <code class="computeroutput"><span class="identifier">group</span><span class="special">::</span><span class="identifier">translate_ranks</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node97.html#Node97" target="_top"><code class="computeroutput"><span class="identifier">MPI_Group_compare</span></code></a>
                </p>
              </td>
<td>
                <p>
                  operators <code class="computeroutput"><span class="special">==</span></code> and
                  <code class="computeroutput"><span class="special">!=</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_IDENT</span></code>
                </p>
              </td>
<td>
                <p>
                  operators <code class="computeroutput"><span class="special">==</span></code> and
                  <code class="computeroutput"><span class="special">!=</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_SIMILAR</span></code>
                </p>
              </td>
<td>
                <p>
                  operators <code class="computeroutput"><span class="special">==</span></code> and
                  <code class="computeroutput"><span class="special">!=</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_UNEQUAL</span></code>
                </p>
              </td>
<td>
                <p>
                  operators <code class="computeroutput"><span class="special">==</span></code> and
                  <code class="computeroutput"><span class="special">!=</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node98.html#Node98" target="_top"><code class="computeroutput"><span class="identifier">MPI_Comm_group</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp43886000-bb">communicator::group</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node98.html#Node98" target="_top"><code class="computeroutput"><span class="identifier">MPI_Group_union</span></code></a>
                </p>
              </td>
<td>
                <p>
                  operator <code class="computeroutput"><span class="special">|</span></code> for groups
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node98.html#Node98" target="_top"><code class="computeroutput"><span class="identifier">MPI_Group_intersection</span></code></a>
                </p>
              </td>
<td>
                <p>
                  operator <code class="computeroutput"><span class="special">&amp;</span></code> for
                  groups
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node98.html#Node98" target="_top"><code class="computeroutput"><span class="identifier">MPI_Group_difference</span></code></a>
                </p>
              </td>
<td>
                <p>
                  operator <code class="computeroutput"><span class="special">-</span></code> for groups
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node98.html#Node98" target="_top"><code class="computeroutput"><span class="identifier">MPI_Group_incl</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/group.html#idp44307168-bb">group::include</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node98.html#Node98" target="_top"><code class="computeroutput"><span class="identifier">MPI_Group_excl</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/group.html#idp44307168-bb">group::exclude</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node98.html#Node98" target="_top"><code class="computeroutput"><span class="identifier">MPI_Group_range_incl</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node98.html#Node98" target="_top"><code class="computeroutput"><span class="identifier">MPI_Group_range_excl</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node99.html#Node99" target="_top"><code class="computeroutput"><span class="identifier">MPI_Group_free</span></code></a>
                </p>
              </td>
<td>
                <p>
                  used automatically in Boost.MPI
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
        Boost.MPI provides manipulation of communicators through the <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html" title="Class communicator">communicator</a></code> class.
      </p>
<div class="table">
<a name="mpi.tutorial.c_mapping.t8"></a><p class="title"><b>Table&#160;19.9.&#160;Communicator operations</b></p>
<div class="table-contents"><table class="table" summary="Communicator operations">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  C Function
                </p>
              </th>
<th>
                <p>
                  Boost.MPI Equivalent
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node101.html#Node101" target="_top"><code class="computeroutput"><span class="identifier">MPI_Comm_size</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp43884512-bb">communicator::size</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node101.html#Node101" target="_top"><code class="computeroutput"><span class="identifier">MPI_Comm_rank</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp43882976-bb">communicator::rank</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node101.html#Node101" target="_top"><code class="computeroutput"><span class="identifier">MPI_Comm_compare</span></code></a>
                </p>
              </td>
<td>
                <p>
                  operators <code class="computeroutput"><span class="special">==</span></code> and
                  <code class="computeroutput"><span class="special">!=</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node102.html#Node102" target="_top"><code class="computeroutput"><span class="identifier">MPI_Comm_dup</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html" title="Class communicator">communicator</a></code>
                  class constructor using <code class="computeroutput"><span class="identifier">comm_duplicate</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node102.html#Node102" target="_top"><code class="computeroutput"><span class="identifier">MPI_Comm_create</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html" title="Class communicator">communicator</a></code>
                  constructor
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node102.html#Node102" target="_top"><code class="computeroutput"><span class="identifier">MPI_Comm_split</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp44122144-bb">communicator::split</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node103.html#Node103" target="_top"><code class="computeroutput"><span class="identifier">MPI_Comm_free</span></code></a>
                </p>
              </td>
<td>
                <p>
                  used automatically in Boost.MPI
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
        Boost.MPI currently provides support for inter-communicators via the <code class="computeroutput"><a class="link" href="../boost/mpi/intercommunicator.html" title="Class intercommunicator">intercommunicator</a></code>
        class.
      </p>
<div class="table">
<a name="mpi.tutorial.c_mapping.t9"></a><p class="title"><b>Table&#160;19.10.&#160;Inter-communicator operations</b></p>
<div class="table-contents"><table class="table" summary="Inter-communicator operations">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  C Function
                </p>
              </th>
<th>
                <p>
                  Boost.MPI Equivalent
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node112.html#Node112" target="_top"><code class="computeroutput"><span class="identifier">MPI_Comm_test_inter</span></code></a>
                </p>
              </td>
<td>
                <p>
                  use <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp42621984-bb">communicator::as_intercommunicator</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node112.html#Node112" target="_top"><code class="computeroutput"><span class="identifier">MPI_Comm_remote_size</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/intercommunicator.html#idp44173888-bb">boost::mpi::intercommunicator::remote_size</a></code>
                  <code class="computeroutput"><span class="identifier">intercommunicator</span><span class="special">::</span><span class="identifier">remote_size</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node112.html#Node112" target="_top"><code class="computeroutput"><span class="identifier">MPI_Comm_remote_group</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/intercommunicator.html#idp44174656-bb">intercommunicator::remote_group</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node113.html#Node113" target="_top"><code class="computeroutput"><span class="identifier">MPI_Intercomm_create</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/intercommunicator.html" title="Class intercommunicator">intercommunicator</a></code>
                  constructor
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node113.html#Node113" target="_top"><code class="computeroutput"><span class="identifier">MPI_Intercomm_merge</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/intercommunicator.html#idp44175488-bb">intercommunicator::merge</a></code>
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
        Boost.MPI currently provides no support for attribute caching.
      </p>
<div class="table">
<a name="mpi.tutorial.c_mapping.t10"></a><p class="title"><b>Table&#160;19.11.&#160;Attributes and caching</b></p>
<div class="table-contents"><table class="table" summary="Attributes and caching">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  C Function/Constant
                </p>
              </th>
<th>
                <p>
                  Boost.MPI Equivalent
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_NULL_COPY_FN</span></code>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_NULL_DELETE_FN</span></code>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_KEYVAL_INVALID</span></code>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node119.html#Node119" target="_top"><code class="computeroutput"><span class="identifier">MPI_Keyval_create</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node119.html#Node119" target="_top"><code class="computeroutput"><span class="identifier">MPI_Copy_function</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node119.html#Node119" target="_top"><code class="computeroutput"><span class="identifier">MPI_Delete_function</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node119.html#Node119" target="_top"><code class="computeroutput"><span class="identifier">MPI_Keyval_free</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node119.html#Node119" target="_top"><code class="computeroutput"><span class="identifier">MPI_Attr_put</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node119.html#Node119" target="_top"><code class="computeroutput"><span class="identifier">MPI_Attr_get</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node119.html#Node119" target="_top"><code class="computeroutput"><span class="identifier">MPI_Attr_delete</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
        Boost.MPI will provide complete support for creating communicators with different
        topologies and later querying those topologies. Support for graph topologies
        is provided via an interface to the <a href="http://www.boost.org/libs/graph/doc/index.html" target="_top">Boost
        Graph Library (BGL)</a>, where a communicator can be created which matches
        the structure of any BGL graph, and the graph topology of a communicator
        can be viewed as a BGL graph for use in existing, generic graph algorithms.
      </p>
<div class="table">
<a name="mpi.tutorial.c_mapping.t11"></a><p class="title"><b>Table&#160;19.12.&#160;Process topologies</b></p>
<div class="table-contents"><table class="table" summary="Process topologies">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  C Function/Constant
                </p>
              </th>
<th>
                <p>
                  Boost.MPI Equivalent
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_GRAPH</span></code>
                </p>
              </td>
<td>
                <p>
                  unnecessary; use <code class="computeroutput">communicator::has_graph_topology</code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_CART</span></code>
                </p>
              </td>
<td>
                <p>
                  unnecessary; use <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp42626416-bb">communicator::has_cartesian_topology</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node133.html#Node133" target="_top"><code class="computeroutput"><span class="identifier">MPI_Cart_create</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node134.html#Node134" target="_top"><code class="computeroutput"><span class="identifier">MPI_Dims_create</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node135.html#Node135" target="_top"><code class="computeroutput"><span class="identifier">MPI_Graph_create</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput">communicator::with_graph_topology</code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node136.html#Node136" target="_top"><code class="computeroutput"><span class="identifier">MPI_Topo_test</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput">communicator::has_graph_topology</code>,
                  <code class="computeroutput"><a class="link" href="../boost/mpi/communicator.html#idp42626416-bb">communicator::has_cartesian_topology</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node136.html#Node136" target="_top"><code class="computeroutput"><span class="identifier">MPI_Graphdims_get</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="reference.html#boost.mpi.num_vertices">num_vertices</a></code>,
                  <code class="computeroutput"><a class="link" href="reference.html#boost.mpi.num_edges">num_edges</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node136.html#Node136" target="_top"><code class="computeroutput"><span class="identifier">MPI_Graph_get</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="reference.html#boost.mpi.vertices">vertices</a></code>,
                  <code class="computeroutput"><a class="link" href="reference.html#boost.mpi.edges">edges</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node136.html#Node136" target="_top"><code class="computeroutput"><span class="identifier">MPI_Cartdim_get</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node136.html#Node136" target="_top"><code class="computeroutput"><span class="identifier">MPI_Cart_get</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node136.html#Node136" target="_top"><code class="computeroutput"><span class="identifier">MPI_Cart_rank</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node136.html#Node136" target="_top"><code class="computeroutput"><span class="identifier">MPI_Cart_coords</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node136.html#Node136" target="_top"><code class="computeroutput"><span class="identifier">MPI_Graph_neighbors_count</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="reference.html#boost.mpi.out_degree">out_degree</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node136.html#Node136" target="_top"><code class="computeroutput"><span class="identifier">MPI_Graph_neighbors</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="reference.html#boost.mpi.out_edges">out_edges</a></code>,
                  <code class="computeroutput"><a class="link" href="reference.html#boost.mpi.adjacent_vertices">adjacent_vertices</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node137.html#Node137" target="_top"><code class="computeroutput"><span class="identifier">MPI_Cart_shift</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node138.html#Node138" target="_top"><code class="computeroutput"><span class="identifier">MPI_Cart_sub</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node139.html#Node139" target="_top"><code class="computeroutput"><span class="identifier">MPI_Cart_map</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node139.html#Node139" target="_top"><code class="computeroutput"><span class="identifier">MPI_Graph_map</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
        Boost.MPI supports environmental inquires through the <code class="computeroutput"><a class="link" href="../boost/mpi/environment.html" title="Class environment">environment</a></code> class.
      </p>
<div class="table">
<a name="mpi.tutorial.c_mapping.t12"></a><p class="title"><b>Table&#160;19.13.&#160;Environmental inquiries</b></p>
<div class="table-contents"><table class="table" summary="Environmental inquiries">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  C Function/Constant
                </p>
              </th>
<th>
                <p>
                  Boost.MPI Equivalent
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_TAG_UB</span></code>
                </p>
              </td>
<td>
                <p>
                  unnecessary; use <code class="computeroutput"><a class="link" href="../boost/mpi/environment.html#idp43956976-bb">environment::max_tag</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_HOST</span></code>
                </p>
              </td>
<td>
                <p>
                  unnecessary; use <code class="computeroutput"><a class="link" href="../boost/mpi/environment.html#idp43960304-bb">environment::host_rank</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_IO</span></code>
                </p>
              </td>
<td>
                <p>
                  unnecessary; use <code class="computeroutput"><a class="link" href="../boost/mpi/environment.html#idp43962464-bb">environment::io_rank</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node143.html#Node147" target="_top"><code class="computeroutput"><span class="identifier">MPI_Get_processor_name</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/environment.html#idp43965184-bb">environment::processor_name</a></code>
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
        Boost.MPI translates MPI errors into exceptions, reported via the <code class="computeroutput"><a class="link" href="../boost/mpi/exception.html" title="Class exception">exception</a></code>
        class.
      </p>
<div class="table">
<a name="mpi.tutorial.c_mapping.t13"></a><p class="title"><b>Table&#160;19.14.&#160;Error handling</b></p>
<div class="table-contents"><table class="table" summary="Error handling">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  C Function/Constant
                </p>
              </th>
<th>
                <p>
                  Boost.MPI Equivalent
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_ERRORS_ARE_FATAL</span></code>
                </p>
              </td>
<td>
                <p>
                  unused; errors are translated into Boost.MPI exceptions
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_ERRORS_RETURN</span></code>
                </p>
              </td>
<td>
                <p>
                  unused; errors are translated into Boost.MPI exceptions
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node148.html#Node148" target="_top"><code class="computeroutput"><span class="identifier">MPI_errhandler_create</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unused; errors are translated into Boost.MPI exceptions
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node148.html#Node148" target="_top"><code class="computeroutput"><span class="identifier">MPI_errhandler_set</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unused; errors are translated into Boost.MPI exceptions
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node148.html#Node148" target="_top"><code class="computeroutput"><span class="identifier">MPI_errhandler_get</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unused; errors are translated into Boost.MPI exceptions
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node148.html#Node148" target="_top"><code class="computeroutput"><span class="identifier">MPI_errhandler_free</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unused; errors are translated into Boost.MPI exceptions
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node148.html#Node148" target="_top"><code class="computeroutput"><span class="identifier">MPI_Error_string</span></code></a>
                </p>
              </td>
<td>
                <p>
                  used internally by Boost.MPI
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node149.html#Node149" target="_top"><code class="computeroutput"><span class="identifier">MPI_Error_class</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/exception.html#idp43970880-bb">exception::error_class</a></code>
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
        The MPI timing facilities are exposed via the Boost.MPI <code class="computeroutput"><a class="link" href="../boost/mpi/timer.html" title="Class timer">timer</a></code> class, which provides
        an interface compatible with the <a href="http://www.boost.org/libs/timer/index.html" target="_top">Boost
        Timer library</a>.
      </p>
<div class="table">
<a name="mpi.tutorial.c_mapping.t14"></a><p class="title"><b>Table&#160;19.15.&#160;Timing facilities</b></p>
<div class="table-contents"><table class="table" summary="Timing facilities">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  C Function/Constant
                </p>
              </th>
<th>
                <p>
                  Boost.MPI Equivalent
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">MPI_WTIME_IS_GLOBAL</span></code>
                </p>
              </td>
<td>
                <p>
                  unnecessary; use <code class="computeroutput"><a class="link" href="../boost/mpi/timer.html#idp44482336-bb">timer::time_is_global</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node150.html#Node150" target="_top"><code class="computeroutput"><span class="identifier">MPI_Wtime</span></code></a>
                </p>
              </td>
<td>
                <p>
                  use <code class="computeroutput"><a class="link" href="../boost/mpi/timer.html#idp44594672-bb">timer::elapsed</a></code> to determine
                  the time elapsed from some specific starting point
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node150.html#Node150" target="_top"><code class="computeroutput"><span class="identifier">MPI_Wtick</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/timer.html#idp44596224-bb">timer::elapsed_min</a></code>
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
        MPI startup and shutdown are managed by the construction and descruction
        of the Boost.MPI <code class="computeroutput"><a class="link" href="../boost/mpi/environment.html" title="Class environment">environment</a></code>
        class.
      </p>
<div class="table">
<a name="mpi.tutorial.c_mapping.t15"></a><p class="title"><b>Table&#160;19.16.&#160;Startup/shutdown facilities</b></p>
<div class="table-contents"><table class="table" summary="Startup/shutdown facilities">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  C Function
                </p>
              </th>
<th>
                <p>
                  Boost.MPI Equivalent
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node151.html#Node151" target="_top"><code class="computeroutput"><span class="identifier">MPI_Init</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/environment.html" title="Class environment">environment</a></code>
                  constructor
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node151.html#Node151" target="_top"><code class="computeroutput"><span class="identifier">MPI_Finalize</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/environment.html" title="Class environment">environment</a></code>
                  destructor
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node151.html#Node151" target="_top"><code class="computeroutput"><span class="identifier">MPI_Initialized</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/environment.html#idp43998064-bb">environment::initialized</a></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node151.html#Node151" target="_top"><code class="computeroutput"><span class="identifier">MPI_Abort</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><a class="link" href="../boost/mpi/environment.html#idp43995680-bb">environment::abort</a></code>
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
        Boost.MPI does not provide any support for the profiling facilities in MPI
        1.1.
      </p>
<div class="table">
<a name="mpi.tutorial.c_mapping.t16"></a><p class="title"><b>Table&#160;19.17.&#160;Profiling interface</b></p>
<div class="table-contents"><table class="table" summary="Profiling interface">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  C Function
                </p>
              </th>
<th>
                <p>
                  Boost.MPI Equivalent
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node153.html#Node153" target="_top"><code class="computeroutput"><span class="identifier">PMPI_</span><span class="special">*</span></code>
                  routines</a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a href="http://www.mpi-forum.org/docs/mpi-11-html/node156.html#Node156" target="_top"><code class="computeroutput"><span class="identifier">MPI_Pcontrol</span></code></a>
                </p>
              </td>
<td>
                <p>
                  unsupported
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break">
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2005-2007 Douglas Gregor,
      Matthias Troyer, Trustees of Indiana University<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">
        http://www.boost.org/LICENSE_1_0.txt </a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="getting_started.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../mpi.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="reference.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
